---
title: Provision a data portal and register it by key
summary: Build an Oracle or SQL Server data portal and register it under a caller-supplied key.
status: draft
owner: SAIF Documentation
last_reviewed: 2026-08-26
library: SAIF.Application
reference_type: embedded
operation_id: provision-a-data-portal-and-register-it-by-key
trigger: Derived manager's OnCreateDataLayer() implementation
---

# Provision a data portal and register it by key

Constructs an Oracle or SQL Server data portal from caller-supplied connection properties and registers
it in the manager's DPI library under a lower-cased key.

| Field | Value |
| --- | --- |
| **Operation ID** | provision-a-data-portal-and-register-it-by-key |
| **Trigger** | Derived manager's `OnCreateDataLayer()` implementation |
| **Inputs** | `DBUser`, `Database`, `Server` properties; a portal key string |
| **Outputs** | An `IDataPortalInfo` registered in the DPI library under the lower-cased key |
| **Primary components** | `ApplicationDataAccess.CreateOraclePortal`, `ApplicationDataAccess.CreateSQLServerPortal`, `AppManagerBase.InjectDPI` |
| **Entry point** | `SAIF.Application/ApplicationDataAccess.vb`, `SAIF.Application/AppManagerBase.vb` |

## Steps

1. Caller sets `DBUser`, `Database`, and (SQL Server only) `Server` on the `ApplicationDataAccess`
   instance; optionally sets `BatchID`.
2. `CreateOraclePortal(inKey)` / `CreateSQLServerPortal(inKey)` copies those values onto the
   `clsEnvironment` and sets `DBMSType` to `Oracle` or `SqlServer` respectively.
3. `ClientID` is seeded from the DAL's client id, then overwritten with `BatchID` when
   `BatchID.Trim.Length > 0`
   ([BR-APP-007](../business-rules.md#br-app-007-database-client-identity-is-the-requesting-user-unless-overridden)).
4. A `clsMSOracleDataPortal(m_Env)` or `clsSQLDataPortal(m_Env, True)` is constructed and handed to
   `DAL.AddDataPortal(portal, portal.PortalID & inKey)`.
5. The returned `IDataPortalInfo` is added to `m_DPILibrary` under `inKey.ToLower`
   ([BR-APP-008](../business-rules.md#br-app-008-a-dpi-key-is-bound-to-exactly-one-portal)); re-using a
   key via the create methods raises an `ArgumentException` rather than replacing the entry, while
   `InjectDPI` silently ignores a duplicate key.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start(["OnCreateDataLayer<br>called"]) --> SetProps["Set DBUser, Database,<br>Server, BatchID"]
	SetProps --> Create["CreateOraclePortal or<br>CreateSQLServerPortal"]
	Create --> ClientId["Resolve ClientID<br>from BatchID or DAL"]
	ClientId --> Build["Construct<br>clsMSOracleDataPortal or<br>clsSQLDataPortal"]
	Build --> Register["AddDataPortal +<br>register under key"]
	Register --> End(["Portal ready<br>for use"])
```

## Failure and edge-case behavior
- Re-registering a DPI key through `CreateOraclePortal` / `CreateSQLServerPortal` raises
  `ArgumentException`; the same key via `InjectDPI` is silently ignored.
- No SQL is issued anywhere in this operation — it only establishes connection context for the
  business layer.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)